home *** CD-ROM | disk | FTP | other *** search
/ Macworld Expo - Develope…Central & Net Innovations / Developer Central and Net Innovators (MacWorld Expo) (January 1999).iso / Developer Central / Metrowerks CodeWarrior / CodeWarrior Pro 4 Release Notes / PowerPlant Notes / PP Standard Dialogs Note < prev   
Encoding:
Text File  |  1998-08-25  |  9.6 KB  |  262 lines  |  [TEXT/CWIE]
  1. ========================================================================
  2. PP Standard Dialogs
  3. ========================================================================
  4.  
  5. Version: PowerPlant 1.9.2
  6. Date:    August 19, 1998
  7. ========================================================================
  8.  
  9. Navigation Services is a new piece of System software that provides
  10. dialogs for opening and saving files. Nav Services is an improvement
  11. on Standard File. Nav Services dialogs are moveable modal and have an
  12. interface similar to that of Finder list views.
  13.  
  14. Nav Services ships as a separate extension for Mac OS 8.1, but will
  15. be part of Mac OS 8.5 (Allegro). Furthermore, Apple has stated that
  16. Mac OS X (Carbon) will not support Standard File. Therefore, you
  17. must update your programs to use Nav Services instead of Standard
  18. File to be Carbon-compatible. For more information, you should
  19. go to Apple's web site at <http://developer.apple.com/sdk/>
  20. and download the Navigation Services SDK.
  21.  
  22. The files in the "Standard Dialogs" implement a common API for
  23. using both Navigation Services and Standard File.
  24.  
  25.  
  26. ========================================================================
  27. New Modules
  28. ========================================================================
  29.  
  30. There are three new modules:
  31.  
  32.     UClassicDialogs        - Always uses Standard File
  33.     UNavServicesDialogs - Always uses Nav Services
  34.     UConditionalDialogs - Use Nav Services if available,
  35.                             otherwise use Standard File
  36.                             
  37. Each module implements the exact same functions and classes, but
  38. wrapped in a namespace to avoid name collisions. This means that
  39. client code for using each module is the same except for the
  40. namespace name.
  41.  
  42. To allow switching between modules without having to change
  43. client code, PowerPlant declares a PP_StandardDialogs namespace
  44. alias that's controlled by a preprocessor symbol. Look at
  45. PP_Macros.h and UStandardDialogs.h to see how the preprocessor
  46. symbol PP_StdDialog_Option determines the namespace to which
  47. the alias refers and selects the proper module.
  48.  
  49. As an example, consider the following code:
  50.  
  51. bool
  52. LDocument::AskConfirmRevert()
  53. {
  54.     Str255    docName;
  55.     
  56.     return PP_StandardDialogs::AskConfirmRevert(GetDescriptor(docName));
  57. }
  58.  
  59. Depending on the declaration of PP_StandardDialogs, the actual
  60. function called is one of:
  61.  
  62.     UClassicDialogs::AskConfirmRevert()
  63.     UNavServicesDialogs::AskConfirmRevert()
  64.     UConditionalDialogs::AskConfirmRevert()
  65.     
  66. Conceptually, a namespace alias is similar to using preprocessor
  67. symbol substitution:
  68.  
  69.     #define    PP_StandardDialogs    UClassicDialogs
  70.     
  71. rather than:
  72.  
  73.     namespace PP_StandardDialogs = UClassicDialogs
  74.     
  75. However, the namespace alias is safer, since it won't interfere
  76. with the (unlikely) use of the name PP_StandardDialogs in
  77. another context.
  78.  
  79. Note that the functions in UClassicDialogs and UNavServicesDialogs
  80. are completely independent. They are do not inherit from a common
  81. base class. The functions in UConditionalDialogs are also unrelated
  82. to the others by inheritance, but they do call the functions in
  83. the other two modules.
  84.  
  85. The window titles for the Open and Save dialogs using NavServices
  86. are stored in strings 3 and 4 in 'STR#' 200. Existing programs
  87. use strings 1 and 2 in this resource are the application name and
  88. the "save as" prompt for StandardFile. If you do not add these
  89. strings, you will get the system default window titles. See the
  90. "PP Copy & Customize.ppob" file for an example.
  91.  
  92.  
  93. ========================================================================
  94. Module Format
  95. ========================================================================
  96.  
  97. Each module implements the following functions:
  98.  
  99.     Load                Preload necessary system facilities
  100.     Unload                Unload system facilities
  101.     
  102.     AskSaveChanges        Ask to save changes before closing/quitting
  103.     AskConfirmRevert    Confirm revert to last saved version
  104.     
  105.     AskOpenOneFile        Ask to select one file to open
  106.     AskChooseOneFile    Ask to select one file (not a document to open)
  107.     AskChooseFolder        Ask to select a folder
  108.     AskChooseVolume        Ask to select a volume
  109.     AskSaveFile            Ask to specify a file for saving a document
  110.     
  111. Note that these functions are within the module namespace, but not
  112. within any class. Without namespaces, it's common to use a class
  113. with all static functions to logically group functions and avoid
  114. polluting the global scope. The PP UTextTraits class does this.
  115.  
  116. With namespaces, there's no need to make a class just to group
  117. functions. You just put the functions in a namespace. However,
  118. the syntax to access the functions remains the same. For example,
  119.  
  120.     class Foo {                // Old way. Class with
  121.         static void Bar();    //   static functions.
  122.         static void Car();
  123.     };
  124.     
  125.     Foo::Bar();                // Call function Bar in class Foo
  126.  
  127.  
  128.     namespace Foo {            // New way. Put functions
  129.         void Bar();            //    in a namespace.
  130.         void Car();
  131.     }
  132.     
  133.     Foo::Bar();                // Call function Bar in namespace Foo
  134.     
  135.  
  136. LDocument uses the AskSaveChanges and AskConfirmRevert functions
  137. to display the standard dialogs to ask the user to confirm an
  138. action which may discard data.
  139.  
  140. The other "ask" functions are simple routines for letting the
  141. user choose or specify a file. They are similar to StandardGetFile
  142. and StandardPutFile.
  143.  
  144. LDocument::AskSaveAs calls AskSaveFile to ask the user to specify
  145. a file for saving the document.
  146.     
  147. To support all the extra options and features that Nav Services
  148. offers beyond Standard File, each module also implements two
  149. helper classes:
  150.  
  151.     LFileChooser        Helper class for choosing files to open
  152.     
  153.     LFileDesignator        Helper class for designating a file for
  154.                             saving a document
  155.  
  156. The Classic versions of these are equivalent to the simple
  157. "ask" functions above. The NavServices versions retain options
  158. and state information that allow you to customize the dialogs
  159. and to use the automatic file translation features.
  160.  
  161.  
  162. ========================================================================
  163. New Files
  164. ========================================================================
  165.  
  166.     UStandardDialogs.h
  167.         Common header file for all modules. #include this header
  168.         in your source files.
  169.     
  170.     UClassicDialogs.h
  171.     UClassicDialogs.cp
  172.         Header and source for UClassicDialogs. Add the .cp file
  173.         to your project if you use the classic or conditional
  174.         dialogs option.
  175.     
  176.     UNavServicesDialogs.h
  177.     UNavServicesDialogs.cp
  178.         Header and source for UNavServicesDialogs. Add the .cp
  179.         file to your project if you use the Nav Services or
  180.         conditional dialogs option.
  181.     
  182.     UConditionalDialogs.h
  183.     UConditionalDialogs.cp
  184.         Header and source for UConditionalDialogs. Add the .cp
  185.         file to your project if you use the conditional dialogs
  186.         option.
  187.     
  188.     UStandardDialogs.i
  189.         Declarations of common functions. #include'd by the
  190.         header for each module. This avoids have to put the
  191.         same function prototypes in each of the three headers.
  192.     
  193.     LFileChooser.i
  194.         Declaration of the LFileChooser class. #include'd by
  195.         header for each module. This avoids have to put the
  196.         same class declaration in each of the three headers.
  197.     
  198.     LFileDesignator.i
  199.         Declaration of the LFileDesignator class. #include'd by
  200.         header for each module. This avoids have to put the
  201.         same class declaration in each of the three headers.
  202.  
  203.  
  204. ========================================================================
  205. Using the Modules
  206. ========================================================================
  207.  
  208. The "TextDoc Demo" program has examples of using the modules.
  209.  
  210. The "ask" functions are the easiest to use. They all pass back
  211. the FSSpec of the file selected by the user. See LDocument::AskSaveAs()
  212. and CTextViewDemoApp::DoInsertFile() for examples.
  213.  
  214. CTextViewDemoApp::ChooseDocument() demonstates using LFileChooser
  215. as a stack-based object, which will be its most common usage.
  216. You might want to store an LFileChooser object if you wish to
  217. specify some custom options that you can re-use when you open
  218. particular kinds of files.
  219.  
  220. The CTextDoc class stores a LFileDesignator object and uses it
  221. when asking the user to save a file. Storing a LFileDesignator
  222. lets you use Nav Services to translate a file in an efficient
  223. manner. Consider this scenario:
  224.  
  225. (1) User creates a new document and enters data
  226. (2) User chooses "save". LFileDesignator calls NavPutFile to
  227.         let the user specify a new file. In doing so, the
  228.         user also chooses a file format which requires translation.
  229. (3) Your program saves the document in its native format and
  230.         not the format selected by the user.
  231. (4) User enters more data and chooses "save"
  232. (5) Your program saves the document in its native format
  233. (6) Steps 4 and 5 repeat as user continues to work on the document
  234. (7) User closes document
  235. (8) If document has changed since last save, you prompt user to
  236.         save the changes. If user chooses to save, you again save
  237.         the document in its native format
  238. (9) Finally, the destructor for LFileDesignator calls
  239.         NavCompleteSave to translate the document into the format
  240.         the user selected in step 2.
  241.         
  242. By defering the translation until step 9, we avoid having to
  243. translate the document each time the user performed an intermediate
  244. save in step 4. Depending on the file formats, translation can
  245. be time consuming. This would be very annoying for users who
  246. frequently save documents while working.
  247.  
  248. However, defering the translation means that we need to store
  249. information from the initial save dialog until the document
  250. closes. Thus, we need to store the LFileDesignator object
  251. rather than using a stack-based object or a simple function call.
  252.  
  253.  
  254. ========================================================================
  255. Known Limitations
  256. ========================================================================
  257.  
  258. * Setting the default location to a Volume does not work using
  259.     Classic Dialogs. The problem seems to be that Standard File
  260.     presents the illusion that volumes are contained within
  261.     the Desktop. In reality, the Desktop is an invisible folder
  262.     within the root volume.